---
title: gluestack-ui FormControl Component | Installation, Usage, and API

description: Provide context to form elements, such as invalid, disabled, or required states.

pageTitle: FormControl

pageDescription: Provide context to form elements, such as invalid, disabled, or required states.

showHeader: true
---

import { Meta } from '@storybook/addon-docs';

<Meta title="with-nativewind/Components/Forms/FormControl" />

import {
  FormControlHelper,
  FormControlError,
  Input,
  Box,
  Center,
  AlertCircleIcon,
  CircleIcon,
  CheckIcon,
  ChevronDownIcon,
  FormControlLabelText,
  FormControlHelperText,
  FormControlErrorIcon,
  FormControlErrorText,
  InputField,
  Text as FormControlText,
  Heading,
  Radio,
  RadioGroup,
  RadioIcon,
  RadioIndicator,
  RadioLabel,
  Checkbox,
  CheckboxGroup,
  CheckboxIndicator,
  CheckboxIcon,
  CheckboxLabel,
  Textarea,
  TextareaInput,
  Select,
  SelectTrigger,
  SelectInput,
  SelectIcon,
  SelectPortal,
  SelectBackdrop,
  SelectContent,
  SelectDragIndicatorWrapper,
  SelectDragIndicator,
  SelectItem,
  Switch,
  Slider,
  SliderTrack,
  SliderFilledTrack,
  SliderThumb,
  Modal,
  ModalBackdrop,
  ModalContent,
  ModalHeader,
  ModalCloseButton,
  ModalBody,
  ModalFooter,
  HStack,
  VStack,
  FormControl,
  FormControlLabel,
  Icon,
  Button,
  ButtonText,
} from '../../core-components/nativewind';
import {
  AppProvider,
  CodePreview,
  Table,
  TableContainer,
  Text,
  InlineCode,
  CollapsibleCode,
  Tabs
} from '@gluestack/design-system';
import { transformedCode } from '../../utils';
import { useState } from 'react';
import Wrapper from '../../core-components/nativewind/Wrapper';
import AnatomyImage from '../../extra-components/nativewind/AnatomyImage';

This is an illustration of **FormControl** component.

<Wrapper>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
        <Box className="h-32 w-72">
          <FormControl {...props}>
            <FormControlLabel className="mb-1">
              <FormControlLabelText>Password</FormControlLabelText>
            </FormControlLabel>
            <Input>
              <InputField
                type="password"
                defaultValue="12345"
                placeholder="password"
              />
            </Input>
            <FormControlHelper>
              <FormControlHelperText>
                Must be at least 6 characters.
              </FormControlHelperText>
            </FormControlHelper>
            <FormControlError>
              <FormControlErrorIcon
                size={10}
                as={AlertCircleIcon}
              />
              <FormControlErrorText>
                At least 6 characters are required.
              </FormControlErrorText>
            </FormControlError>
          </FormControl>
        </Box>
      `,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: {
        Wrapper,
        FormControl,
        FormControlLabel,
        FormControlLabelText,
        FormControlHelper,
        FormControlHelperText,
        FormControlError,
        FormControlErrorIcon,
        FormControlErrorText,
        Icon,
        Input,
        InputField,
        AlertCircleIcon,
        Box,
      },
      argsType: {},
    }}
  />
</Wrapper>

#### Form Control with Radio

The Radio Component can be incorporated within the FormControl.

<Wrapper>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
        <FormControl>
          <FormControlLabel>
            <FormControlLabelText>
              Favourite fruit
            </FormControlLabelText>
          </FormControlLabel>
          <RadioGroup className='my-2'>
            <VStack space="sm">
              <Radio size="sm" value="Mango">
                <RadioIndicator>
                  <RadioIcon>
                    <CircleIcon/>
                  </RadioIcon>
                </RadioIndicator>
                <RadioLabel>
                  Mango
                </RadioLabel>
              </Radio>
              <Radio size="sm" value="Apple">
                <RadioIndicator>
                  <RadioIcon>
                    <CircleIcon/>
                  </RadioIcon>
                </RadioIndicator>
                <RadioLabel>
                  Apple
                </RadioLabel>
              </Radio>
              <Radio size="sm" value="Orange">
                <RadioIndicator>
                  <RadioIcon>
                    <CircleIcon/>
                  </RadioIcon>
                </RadioIndicator>
                <RadioLabel>
                  Orange
                </RadioLabel>
              </Radio>
            </VStack>
          </RadioGroup>
          <FormControlHelper>
            <FormControlHelperText>
              Choose the fruit you like the most
            </FormControlHelperText>
          </FormControlHelper>
        </FormControl>
      `,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: {
        Wrapper,
        FormControl,
        FormControlLabel,
        FormControlLabelText,
        FormControlHelper,
        FormControlHelperText,
        FormControlError,
        FormControlErrorIcon,
        FormControlErrorText,
        Icon,
        Radio,
        RadioGroup,
        RadioIcon,
        RadioIndicator,
        RadioLabel,
        AlertCircleIcon,
        VStack,
        CircleIcon,
        Heading,
      },
      argsType: {},
    }}
  />
</Wrapper>

<br />

## Installation

<Tabs value="cli" type="section">
  <Tabs.TabList>
      <Tabs.Tab value="cli">
        <Tabs.TabTitle>CLI</Tabs.TabTitle>
      </Tabs.Tab>
     <Tabs.Tab value="manual">
        <Tabs.TabTitle>Manual</Tabs.TabTitle>
     </Tabs.Tab>
  </Tabs.TabList>
  <Tabs.TabPanels>
    <Tabs.TabPanel value="cli">
<>

### Run the following command:
  ```bash
  npx gluestack-ui add form-control
  ```
</>
    </Tabs.TabPanel>
    <Tabs.TabPanel value="manual"> 
<>

### Step 1: Install the following dependencies:
```bash
npm i @gluestack-ui/form-control
```

### Step 2: Copy and paste the following code into your project.
<CollapsibleCode>

```jsx 
%%-- File: core-components/nativewind/form-control/index.tsx --%% 
```
</CollapsibleCode>

### Step 3: Update the import paths to match your project setup.
</>
    </Tabs.TabPanel>
  </Tabs.TabPanels>
</Tabs>

## API Reference

To use this component in your project, include the following import statement in your file.

```jsx
import { FormControl } from '@/components/ui/form-control';
```

<AnatomyImage mobileUrl='https://i.imgur.com/qDJSDGA.png' webUrl='https://i.imgur.com/jbkdJ4q.png' classNameStyle='aspect-[513/534] md:aspect-[736/378]' />

```jsx
export default () => (
  <FormControl>
    <FormControlLabel>
      <FormControlLabelText />
    </FormControlLabel>
    <FormControlHelper>
      <FormControlHelperText />
    </FormControlHelper>
    <FormControlError>
      <FormControlErrorIcon />
      <FormControlErrorText />
    </FormControlError>
  </FormControl>
);
```

### Component Props

This section provides a comprehensive reference list for the component props, detailing descriptions, properties, types, and default behavior for easy project integration.

#### FormControl

It inherits all the properties of React Native's [View](https://reactnative.dev/docs/view) component.

<>
  <TableContainer>
    <Table>
      <Table.THead>
        <Table.TR>
          <Table.TH>
            <Table.TText>Prop</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Type</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Default</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Description</Table.TText>
          </Table.TH>
        </Table.TR>
      </Table.THead>
      <Table.TBody>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>isInvalid</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>bool</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`When true, invalid state.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>isRequired</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>bool</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`If true, astrick gets activated.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>isDisabled</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>bool</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`Disabled state true.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>isReadOnly</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>bool</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`To manually set read-only state.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>isDisabled</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>bool</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`To manually set disable to the FormControl.`}</Table.TText>
          </Table.TD>
        </Table.TR>
      </Table.TBody>
    </Table>
  </TableContainer>
</>

#### FormControlLabel

It inherits all the properties of React Native's [View](https://reactnative.dev/docs/view) component.

#### FormControlLabelText

It inherits all the properties of React Native's [Text](https://reactnative.dev/docs/text) component.

#### FormControlHelper

It inherits all the properties of React Native's [View](https://reactnative.dev/docs/view) component.

#### FormControlHelperText

It inherits all the properties of React Native's [Text](https://reactnative.dev/docs/text) component.

#### FormControlError

It inherits all the properties of React Native's [View](https://reactnative.dev/docs/view) component.

#### FormControlErrorIcon

It inherits all the properties of gluestack Style's [AsForwarder](/style/docs/api/as-forwarder) component.

#### FormControlErrorText

It inherits all the properties of React Native's [Text](https://reactnative.dev/docs/text) component.

### Features

- Keyboard support for actions.
- Support for hover, focus and active states.
- Option to add your styles or use the default styles.

### Props

FormControl component is created using View component from react-native. It extends all the props supported by [React Native View](https://reactnative.dev/docs/view#props).

### Examples

The Examples section provides visual representations of the different variants of the component, allowing you to quickly and easily determine which one best fits your needs. Simply copy the code and integrate it into your project.

#### Form Control with Input

The Input Component can be incorporated within the FormControl.

<Wrapper>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={true}
    metaData={{
      code: `
        <Box className="h-32 w-72">
          <FormControl {...props}>
            <FormControlLabel className="mb-1">
              <FormControlLabelText>Password</FormControlLabelText>
            </FormControlLabel>
            <Input>
              <InputField
                type="password"
                defaultValue="12345"
                placeholder="password"
              />
            </Input>
            <FormControlHelper>
              <FormControlHelperText>
                Must be at least 6 characters.
              </FormControlHelperText>
            </FormControlHelper>
            <FormControlError>
              <FormControlErrorIcon
                size={10}
                as={AlertCircleIcon}
              />
              <FormControlErrorText>
                At least 6 characters are required.
              </FormControlErrorText>
            </FormControlError>
          </FormControl>
        </Box>
      `,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: {
        Wrapper,
        FormControl,
        FormControlLabel,
        FormControlLabelText,
        FormControlHelper,
        FormControlHelperText,
        FormControlError,
        FormControlErrorIcon,
        FormControlErrorText,
        Icon,
        Input,
        InputField,
        AlertCircleIcon,
        Box,
      },
      argsType: {
        size: {
          control: 'select',
          options: ['sm', 'md', 'lg'],
          default: 'md',
        },
        isDisabled: {
          control: 'boolean',
          default: false,
        },
        isInvalid: {
          control: 'boolean',
          default: false,
        },
        isReadOnly: {
          control: 'boolean',
          default: false,
        },
        isRequired: {
          control: 'boolean',
          default: false,
        },
      },
    }}
  />
</Wrapper>

#### Form Control with Checkbox

The Checkbox Component can be incorporated within the FormControl.

<Wrapper>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
        <FormControl>
          <FormControlLabel>
            <FormControlLabelText>
              Sign up for newsletters
            </FormControlLabelText>
          </FormControlLabel>
          <CheckboxGroup className='my-2'>
            <VStack space="sm">
              <Checkbox size="sm" value="Mango">
                <CheckboxIndicator className='mr-2'>
                  <CheckboxIcon>
                    <CheckIcon />
                  </CheckboxIcon>
                </CheckboxIndicator>
                <CheckboxLabel>
                  Daily Bits
                </CheckboxLabel>
              </Checkbox>
              <Checkbox size="sm" value="Apple">
                <CheckboxIndicator className='mr-2'>
                  <CheckboxIcon>
                    <CheckIcon />
                  </CheckboxIcon>
                </CheckboxIndicator>
                <CheckboxLabel>
                  Event Updates
                </CheckboxLabel>
              </Checkbox>
              <Checkbox size="sm" value="Orange">
                <CheckboxIndicator className='mr-2'>
                  <CheckboxIcon>
                    <CheckIcon />
                  </CheckboxIcon>
                </CheckboxIndicator>
                <CheckboxLabel>
                  Sponsorship
                </CheckboxLabel>
              </Checkbox>
            </VStack>
          </CheckboxGroup>
          <FormControlHelper>
            <FormControlHelperText>
              Subscribe to newsletters for updates
            </FormControlHelperText>
          </FormControlHelper>
        </FormControl>
      `,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: {
        Wrapper,
        FormControl,
        FormControlLabel,
        FormControlLabelText,
        FormControlHelper,
        FormControlHelperText,
        FormControlError,
        FormControlErrorIcon,
        FormControlErrorText,
        Icon,
        Checkbox,
        CheckboxGroup,
        CheckboxIndicator,
        CheckboxIcon,
        CheckboxLabel,
        AlertCircleIcon,
        VStack,
        CheckIcon,
        Heading,
      },
      argsType: {},
    }}
  />
</Wrapper>

#### Form Control with Textarea

The Textarea Component can be incorporated within the FormControl.

<Wrapper>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
        <FormControl>
          <FormControlLabel>
            <FormControlLabelText>
              Comment
            </FormControlLabelText>
          </FormControlLabel>
          <Textarea>
            <TextareaInput />
          </Textarea>
          <FormControlHelper >
            <FormControlHelperText>
              Type your comment above
            </FormControlHelperText>
          </FormControlHelper>
        </FormControl>
      `,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: {
        Wrapper,
        FormControl,
        FormControlLabel,
        FormControlLabelText,
        FormControlHelper,
        FormControlHelperText,
        FormControlError,
        FormControlErrorIcon,
        FormControlErrorText,
        Icon,
        Textarea,
        TextareaInput,
        AlertCircleIcon,
      },
      argsType: {},
    }}
  />
</Wrapper>

#### Form Control with Error

Error messages can be displayed using FormControl.

<Wrapper>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
        <FormControl isInvalid>
          <FormControlLabel>
            <FormControlLabelText>
              Which time slot works best for you?
            </FormControlLabelText>
          </FormControlLabel>
          <RadioGroup className='my-2'>
            <VStack space="sm">
              <Radio size="sm" value="Mango">
                <RadioIndicator>
                  <RadioIcon as={CircleIcon} />
                </RadioIndicator>
                <RadioLabel>
                  Monday
                </RadioLabel>
              </Radio>
              <Radio size="sm" value="Apple">
                <RadioIndicator>
                  <RadioIcon as={CircleIcon} />
                </RadioIndicator>
                <RadioLabel>
                  Tuesday
                </RadioLabel>
              </Radio>
              <Radio size="sm" value="Orange">
                <RadioIndicator>
                  <RadioIcon as={CircleIcon} />
                </RadioIndicator>
                <RadioLabel>
                  Wednesday
                </RadioLabel>
              </Radio>
            </VStack>
          </RadioGroup>
          <FormControlError>
            <FormControlErrorIcon as={AlertCircleIcon}/>
            <FormControlErrorText>
              Choose one time slot for the meeting
            </FormControlErrorText>
          </FormControlError>
        </FormControl>
      `,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: {
        Wrapper,
        FormControl,
        FormControlLabel,
        FormControlLabelText,
        FormControlHelper,
        FormControlHelperText,
        FormControlError,
        FormControlErrorIcon,
        FormControlErrorText,
        Icon,
        Radio,
        RadioGroup,
        RadioIcon,
        RadioIndicator,
        RadioLabel,
        AlertCircleIcon,
        VStack,
        CircleIcon,
        Heading,
      },
      argsType: {},
    }}
  />
</Wrapper>

#### Form Control with Form Actions

Form Action Buttons can also be utilized in conjunction with FormControl.

<Wrapper>
  <CodePreview
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
        <HStack>
          <FormControl>
            <Button variant='outline' action='secondary'>
              <ButtonText>
                Cancel
              </ButtonText>
            </Button>
          </FormControl>
               <FormControl>
            <Button action='negative' className='ml-4'>
              <ButtonText className="text-white group-hover/button:text-white group-active/button:text-white">
                Delete
              </ButtonText>
            </Button>
          </FormControl>
        </HStack>
      `,
      transformCode: (code) => {
        return transformedCode(code);
      },
      scope: {
        Wrapper,
        FormControl,
        FormControlLabel,
        FormControlLabelText,
        FormControlHelper,
        FormControlHelperText,
        FormControlError,
        FormControlErrorIcon,
        FormControlErrorText,
        HStack,
        Button,
        ButtonText,
      },
      argsType: {},
    }}
  />
</Wrapper>
